---
id: workflow
title: tctl v1.17 workflow command reference
sidebar_label: workflow
description: The public preview of Temporal CLI is now available! Begin using it and provide feedback. After the full release, tctl will deprecate. Perform various Workflow operations using tctl commands.
toc_max_heading_level: 4
keywords:
  - cli
  - cli reference
  - tctl
  - temporal
  - temporal cli
  - temporal server
---

:::info Temporal CLI is now available

The public preview of [Temporal CLI](/cli) is now available.
We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

:::

The `tctl workflow` commands enable [Workflow Execution](/workflows#workflow-execution) operations.

- [tctl workflow cancel](#cancel)
- [tctl workflow count](#count)
- [tctl workflow describe](#describe)
- [tctl workflow describeid](#describeid)
- [tctl workflow list](#list)
- [tctl workflow listall](#listall)
- [tctl workflow listarchived](#listarchived)
- [tctl workflow observe](#observe)
- [tctl workflow observeid](#observeid)
- [tctl workflow query](#query)
- [tctl workflow reset](#reset)
- [tctl workflow reset-batch](#reset-batch)
- [tctl workflow run](#run)
- [tctl workflow scan](#scan)
- [tctl workflow show](#show)
- [tctl workflow showid](#showid)
- [tctl workflow signal](#signal)
- [tctl workflow stack](#stack)
- [tctl workflow start](#start)
- [tctl workflow terminate](#terminate)

## cancel

The `tctl workflow cancel --query` command cancels a [Workflow Execution](/workflows#workflow-execution).

Canceling a running Workflow Execution records a `WorkflowExecutionCancelRequested` event in the History.
A new [Workflow Task](/workers#workflow-task) will be scheduled.
After cancellation, the Workflow Execution can perform cleanup work.

See also [`tctl workflow terminate --query`](#terminate).

`tctl workflow cancel --query <query> <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow cancel --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow cancel --run_id <id>
```

## count

The `tctl workflow count` command counts [Workflow Executions](/workflows#workflow-execution).
This command requires Elasticsearch to be enabled.

`tctl workflow count <modifiers>`

The following modifier controls the behavior of the command.

### --query

_Required modifier_

Specify an SQL-like query of [Search Attributes](/visibility#search-attribute).

Alias: `-q`

**Example**

To count all open [Workflow Executions](/workflows#workflow-execution):

```bash
tctl workflow count --query 'ExecutionStatus="Running"'
```

## describe

The `tctl workflow describe` command shows information about a [Workflow Execution](/workflows#workflow-execution).
This information can be used to locate a failed Workflow Execution, for example.

To find a Workflow with a given Run Id, refer to [`tctl workflow describeid`](#describeid).

`tctl workflow describe <modifiers>`

The following modifiers control the behavior of the command.
Always include required modifiers when executing this command.

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow describe --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).
If a Run Id is not provided, the command will show the latest Workflow Execution of that Workflow Id.

Alias: `-r`

**Example**

```bash
tctl workflow describe --run_id <id>
```

### --print_raw

Print properties exactly as they are stored.

**Example**

```bash
tctl workflow describe --print_raw
```

### --reset_points_only

Show only events that are eligible for reset.
If successful, the command returns the Run Id of all deployments, and the times at which the Events were created.

**Example**

```bash
tctl workflow describe --reset_points_only
```

## describeid

The `tctl workflow describeid` command shows information about a [Workflow Execution](/workflows#workflow-execution) for the specified [Workflow Id](/workflows#workflow-id) and optional [Run Id](/workflows#run-id).

`tctl workflow describeid <workflow_id> <run_id> <modifiers>`

This command is a shortcut for `tctl workflow describe --workflow_id <workflowid> --run_id <runid>`.

The following modifiers control the behavior of the command.

### --print_raw

Print properties exactly as they are stored.

**Example**

```bash
tctl workflow describeid <workflow_id> <id> --print_raw
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow describeid <workflow_id> --reset_points_only
```

## list

The `tctl workflow list` command lists open or closed [Workflow Executions](/workflows#workflow-execution).

By default, this command lists a maximum of 10 closed Workflow Executions.

- To set the size of a page, use the `--pagesize` option.
- To list multiple pages, use the `--more` option.
- To list open Workflow Executions, use the `--open` option.

See also [`tctl workflow listall`](#listall), [`tctl workflow listarchived`](#listarchived), and [`tctl workflow scan`](#scan).

`tctl workflow list <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow list --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow list --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow list --print_memo
```

### --print_search_attr

Print the [Search Attributes](/visibility#search-attribute).

**Example**

```bash
tctl workflow list --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow list --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow list --print_json
```

### --open

List open [Workflow Executions](/workflows#workflow-execution).
(By default, the `tctl workflow list` command lists closed Workflow Executions.)

**Example**

```bash
tctl workflow list --open
```

### --earliest_time

Specify the earliest start time to list.
Supported format are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 3:04:05 PM India Standard Time on January 2, 2022:

```bash
tctl workflow list --earliest-time '2022-01-02T15:04:05+05:30'
```

To specify 15 minutes before the current time:

```bash
tctl workflow list --earliest-time '15minute'
```

### --latest_time

Specify the latest start time to list.
Supported formats are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 11:02:17 PM Pacific Daylight Time on April 13, 2022:

```bash
tctl workflow list --latest_time '2022-04-13T23:02:17-07:00'
```

To specify 10s before the current time:

```bash
tctl workflow list --latest_time '10second'
```

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow list --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflows#workflow-type).

**Example**

```bash
tctl workflow list --workflow_type <name>
```

### --status

Specify the status of a [Workflow Execution](/workflows#workflow-execution).
Supported values are as follows:

- `completed`
- `failed`
- `canceled`
- `terminated`
- `continuedasnew`
- `timedout`

**Example**

```bash
tctl workflow list --status <value>
```

### --query

**How to list and filter Workflow Executions with a [List Filter](/visibility#list-filter) using tctl.**

The `--query` flag is supported only when [Advanced Visibility](/visibility#advanced-visibility) is configured with the Cluster.

Using the `--query` option causes tctl to ignore all other filter options, including `open`, `earliest_time`, `latest_time`, `workflow_id`, and `workflow_type`.

Alias: `-q`

**Example**

```bashbash
tctl workflow list --query "WorkflowId=<your-workflow-id>"
```

More examples:

```bashbash
tctl workflow list \
  --query "WorkflowType='main.SampleParentWorkflow' AND ExecutionStatus='Running'"
```

```bashbash
tctl workflow list \
  --query '(CustomKeywordField = "keyword1" and CustomIntField >= 5) or CustomKeywordField = "keyword2"' \
  --print_search_attr
```

```bashbash
tctl workflow list \
  --query 'CustomKeywordField in ("keyword2", "keyword1") and CustomIntField >= 5 and CloseTime between "2018-06-07T16:16:36-08:00" and "2019-06-07T16:46:34-08:00" order by CustomDatetimeField desc' \
  --print_search_attr
```

```bashbash
tctl workflow list \
  --query 'WorkflowType = "main.Workflow" and (WorkflowId = "1645a588-4772-4dab-b276-5f9db108b3a8" or RunId = "be66519b-5f09-40cd-b2e8-20e4106244dc")'
```

```bashbash
tctl workflow list \
  --query 'WorkflowType = "main.Workflow" StartTime > "2019-06-07T16:46:34-08:00" and ExecutionStatus = "Running"'
```

### --more

List more than one page.
(By default, the `tctl workflow list` command lists one page of results.)

**Example**

```bash
tctl workflow list --more
```

### --pagesize

Specify the maximum number of [Workflow Executions](/workflows#workflow-execution) to list on a page.
(By default, the `tctl workflow list` command lists 10 Workflow Executions per page.)

**Example**

```bash
tctl workflow list --pagesize <value>
```

## listall

The `tctl workflow listall` command lists all open or closed [Workflow Executions](/workflows#workflow-execution).

By default, this command lists all closed Workflow Executions.
To list open Workflow Executions, use the `--open` option.

See also [`tctl workflow list`](#list), [`tctl workflow listarchived`](#listarchived), and [`tctl workflow scan`](#scan).

`tctl workflow listall <modifiers>`

The following modifiers control the behavior of the command.

###`--print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow listall --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow listall --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow listall --print_memo
```

### --print_search_attr

Print the [Search Attributes](/visibility#search-attribute).

**Example**

```bash
tctl workflow listall --print_search_attr
```

### `--print_full`

Print the full message without table formatting.

**Example**

```bash
tctl workflow listall --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow listall --print_json
```

### --open

List open [Workflow Executions](/workflows#workflow-execution).
(By default, the `tctl workflow listall` command lists closed Workflow Executions.)

**Example**

```bash
tctl workflow listall --open
```

### --earliest_time

Specify the earliest start time to list. Supported format are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 3:04:05 PM India Standard Time on January 2, 2022:

```bash
tctl workflow listall --earliest-time '2022-01-02T15:04:05+05:30'
```

To specify 15 minutes before the current time:

```bash
tctl workflow listall --earliest-time '15minute'
```

### --latest_time

Specify the latest start time to list. Supported formats are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

Alias: `--lt`

**Examples**

To specify 11:02:17 PM Pacific Daylight Time on April 13, 2022:

```bash
tctl workflow listall --latest-time '2022-04-13T23:02:17-07:00'
```

To specify 10 seconds before the current time:

```bash
tctl workflow listall --latest-time '10second'
```

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow listall --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflows#workflow-type).

**Example**

```bash
tctl workflow listall --workflow_type <name>
```

### --status

Specify the status of a [Workflow Execution](/workflows#workflow-execution).
Supported values are as follows:

- `completed`
- `failed`
- `canceled`
- `terminated`
- `continuedasnew`
- `timedout`

**Example**

```bash
tctl workflow listall --status <value>
```

### --query

Specify an SQL-like query of [Search Attributes](/visibility#search-attribute).

Using the `--query` option causes tctl to ignore all other filter options, including `open`, `earliest_time`, `latest_time`, `workflow_id`, and `workflow_type`.

Alias: `-q`

**Example**

```bash
tctl workflow listall --query <value>
```

## listarchived

The `tctl workflow listarchived` command lists archived [Workflow Executions](/workflows#workflow-execution).

By default, this command lists a maximum of 100 Workflow Executions.

- To set the size of a page, use the `--pagesize` option.
- To list all pages, use the `--all` option.

See also [`tctl workflow list`](#list), [`tctl workflow listall`](#listall), and [`tctl workflow scan`](#scan).

`tctl workflow listarchived <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow listarchived --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow listarchived --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow listarchived --print_memo
```

### --print_search_attr

Print the [Search Attributes](/visibility#search-attribute).

**Example**

```bash
tctl workflow listarchived --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow listarchived --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow listarchived --print_json
```

### --query

Specify an SQL-like query of [Search Attributes](/visibility#search-attribute).

Consult the documentation of the visibility archiver that is used by your [Namespace](/namespaces) for detailed instructions.

Alias: `-q`

**Example**

```bash
tctl workflow listarchived --query <value>
```

### --pagesize

Specify the maximum number of [Workflow Executions](/workflows#workflow-execution) to list on a page.
(By default, the `tctl workflow listarchived` command lists 100 Workflow Executions per page.)

**Example**

```bash
tctl workflow listarchived --pagesize <value>
```

### --all

List all pages.

**Example**

```bash
tctl workflow listarchived --all
```

## observe

The `tctl workflow observe` command shows the progress of the [Event History](/workflows#event-history) of a [Workflow Execution](/workflows#workflow-execution).

See also [`tctl workflow observeid`](#observeid).

`tctl workflow observe <modifiers>`

Alias: `o`

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow observe --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow observe --run_id <id>
```

### --show_detail

Show event details.

**Example**

```bash
tctl workflow observe --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow observe --max_field_length <length>
```

## observeid

The `tctl workflow observeid` command shows the progress of the [Event History](/workflows#event-history) of a [Workflow Execution](/workflows#workflow-execution) for the specified [Workflow Id](/workflows#workflow-id) and optional [Run Id](/workflows#run-id).

`tctl workflow observeid <workflow_id> [<run_id>] <modifiers>`

This command is a shortcut for `tctl workflow observe --workflow_id <workflowid> [--run_id <runid>]`.

The following modifiers control the behavior of the command.

### --show_detail

Show event details.

**Example**

```bash
tctl workflow observeid --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow observeid --max_field_length <length>
```

## query

Alias: `q`

The `tctl workflow query` command sends a [Query](/encyclopedia/workflow-message-passing#sending-queries) to a [Workflow Execution](/workflows#workflow-execution).

Queries can be used to retrieve all or part of the Workflow state with given parameters.

```bash
$ tctl workflow query --workflow_id "HelloQuery" --query_type "getCount"
Query result as JSON:
3
```

Queries can also be used on completed Workflows.
Let's complete a Workflow by updating its greeting, and then query the now-finished Workflow.

```bash
$ tctl workflow signal --workflow_id "HelloQuery" --name "updateGreeting" --input \"Bye\"
Signal workflow succeeded.
$ tctl workflow query --workflow_id "HelloQuery" --query_type "getCount"
Query result as JSON:
4
```

Queries are written as follows:

`tctl workflow query --workflow_id [modifiers]`

The following modifiers control the behavior of the command.
Always include required modifiers when executing this command.

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id). **This modifier is required.**

Alias: `-w`

**Example**

```bash
tctl workflow query --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow query --run_id <id>
```

### --query_type

Specify the type of Query to run.

**Example**

```bash
tctl workflow query --query_type <value>
```

### --input

Pass input for the Query.
Input must be in JSON format.
For multiple JSON objects, concatenate them and use spaces as separators.

Alias: `-i`

**Example**

```bash
tctl workflow query --input <json>
```

### --input_file

Pass input for the Query from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow query --input_file <filename>
```

### --query_reject_condition

Reject Queries based on Workflow state.
Valid values are `not_open` and `not_completed_cleanly`.

**Example**

```bash
tctl workflow query --query_reject_condition <value>
```

## reset

The `tctl workflow reset` command resets a [Workflow Execution](/workflows#workflow-execution) by either [`eventId`](#--event_id)or [`resetType`](#--reset_type).

Resetting a Workflow allows the process to be resumed from a certain point without losing your parameters or Event History.

To run multiple Reset operations at once, see [`tctl workflow reset-batch`](#reset-batch).

`tctl workflow reset <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow reset --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow reset --run_id <id>
```

### --event_id

Specify the `eventId` of any event after `WorkflowTaskStarted` to which you want to reset.
Valid values are `WorkflowTaskCompleted`, `WorkflowTaskFailed`, and `WorkflowTaskTimeout`.

**Example**

```bash
tctl workflow reset --event_id <id>
```

### --reason

Specify a reason for resetting the [Workflow Execution](/workflows#workflow-execution).

**Example**

```bash
tctl workflow reset --reason <string>
```

### --reset_type

Specify the event type to which you want to reset.

| Value                | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `FirstWorkflowTask`  | Reset to the beginning of the Event History.                |
| `LastWorkflowTask`   | Reset to the end of the Event History.                      |
| `LastContinuedAsNew` | Reset to the end of the Event History for the previous Run. |
| `BadBinary`          | Reset to the point where a bad binary was used.             |

**Example**

```bash
tctl workflow reset --reset_type <value>
```

### --reset_reapply_type

Specify the types of events to reapply after the reset point.
Valid values are `All`, `Signal`, and `None`. The default is `All`.

**Example**

```bash
tctl workflow reset --reset_reapply_type <value>
```

### --reset_bad_binary_checksum

Specify the binary checksum when using `--reset_type BadBinary`.

**Example**

```bash
tctl workflow reset --reset_bad_binary_checksum <value>
```

## reset-batch

The `tctl workflow reset-batch` command resets a batch of [Workflow Executions](/workflows#workflow-execution) by [`resetType`](#--reset_type).

Resetting a Workflow allows the process to be resumed from a certain point without losing your parameters or Event History.

To reset individual Workflows, see [`tctl workflow reset`](#reset).

`tctl workflow reset-batch <modifiers>`

The following modifiers control the behavior of the command.

### --input_file

Provide an input file that specifies [Workflow Execution](/workflows#workflow-execution) to reset.

Each line contains one [Workflow Id](/workflows#workflow-id) as the base Run and, optionally, a [Run Id](/workflows#run-id).
If a Run Id is not specified, the current Run Id is used.

**Example**

```bash
tctl workflow reset-batch --input_file <filename>
```

### --query

Specify an SQL-like query of [Search Attributes](/visibility#search-attribute) describing the [Workflow Executions](/workflows#workflow-execution) to reset.

Alias: `-q`

**Example**

```bash
tctl workflow reset-batch --query <value>
```

### --exclude_file

Provide an input file that specifies [Workflow Executions](/workflows#workflow-execution) to exclude from resetting.

Each line contains one [Workflow Id](/workflows#workflow-id).

**Example**

```bash
tctl workflow reset-batch --exclude_file <filename>
```

### --input_separator

Specify the separator for the input file.
The default is a tab (`\t`).

**Example**

```bash
tctl workflow reset-batch --input_separator <string>
```

### --reason

Specify a reason for resetting the [Workflow Executions](/workflows#workflow-execution).

**Example**

```bash
tctl workflow reset-batch --reason <string>
```

### --input_parallism

Specify the number of goroutines to run in parallel.
Each goroutine processes one line for every second.
The default is 1.

**Example**

```bash
tctl workflow reset-batch --input_parallism <value>
```

### --skip_current_open

Indicate that a [Workflow Execution](/workflows#workflow-execution) should be skipped if the current Run is open for the same [Workflow Id](/workflows#workflow-id) as the base Run.

**Example**

```bash
tctl workflow reset-batch --skip_current_open
```

### --skip_base_is_not_current

Indicate that a [Workflow Execution](/workflows#workflow-execution) should be skipped if the base Run is not the current Run.

**Example**

```bash
tctl workflow reset-batch --skip_base_is_not_current
```

### --only_non_deterministic

Indicate that a [Workflow Execution](/workflows#workflow-execution) should be reset only if its last event is `WorkflowTaskFailed` with a nondeterminism error.

**Example**

```bash
tctl workflow reset-batch --only_non_deterministic
```

### --dry_run

Simulate use of the `tctl workflow reset-batch` command without resetting any [Workflow Executions](/workflows#workflow-execution).
Output is logged to `stdout`.

**Example**

```bash
tctl workflow reset-batch --dry_run
```

### --reset_type

Specify the event type to which you want to reset.

| Value                | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `FirstWorkflowTask`  | Reset to the beginning of the Event History.                |
| `LastWorkflowTask`   | Reset to the end of the Event History.                      |
| `LastContinuedAsNew` | Reset to the end of the Event History for the previous Run. |
| `BadBinary`          | Reset to the point where a bad binary was used.             |

**Example**

```bash
tctl workflow reset-batch --reset_type <value>
```

### --reset_bad_binary_checksum

Specify the binary checksum when using `--reset_type BadBinary`.

**Example**

```bash
tctl workflow reset-batch --reset_bad_binary_checksum <value>
```

## run

The `tctl workflow run` command starts a new [Workflow Execution](/workflows#workflow-execution) and can show the progress of a Workflow Execution.
The command is entered in the following format:

`tctl workflow run <modifiers>`

To run a Workflow, the user must specify the following:

- Task queue name (`--taskqueue`)
- Workflow Type (`--workflow_type`)

```bash
tctl workflow run --taskqueue your-task-queue-name --workflow_type YourWorkflowDefinitionName
```

Single quotes (`''`) are used to wrap input as JSON.
This command doesn't finish until the Workflow completes.

The following modifiers control the behavior of the command.

### --taskqueue

Specify a [Task Queue](/workers#task-queue).

Alias: `--t`

**Example**

```bash
tctl workflow run --taskqueue <name>
```

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow run --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflows#workflow-type).

**Example**

```bash
tctl workflow run --workflow_type <name>
```

### --execution_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Execution](/workflows#workflow-execution) in seconds.
The default value is 0.

**Example**

```bash
tctl workflow run --execution_timeout <seconds>
```

### --workflow_task_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/workers#workflow-task) in seconds.
The default value is 10.

**Example**

```bash
tctl workflow run --workflow_task_timeout <seconds>
```

### --cron

Specify a [Cron Schedule](/workflows#cron-schedules).

**Example**

```bash
tctl workflow run --cron <string>
```

### --workflowidreusepolicy

Specify a [Workflow Id Reuse Policy](/workflows#workflow-id-reuse-policy).
Configure if the same [Workflow Id](/workflows#workflow-id) is allowed for use in new [Workflow Execution](/workflows#workflow-execution).

There are three allowed values:

- [AllowDuplicateFailedOnly](/workflows#workflow-id-reuse-policy)
- [AllowDuplicate](/workflows#workflow-id-reuse-policy)
- [RejectDuplicate](/workflows#workflow-id-reuse-policy)

**Examples**

```bash
tctl workflow run --workflowidreusepolicy AllowDuplicate
tctl workflow run --workflowidreusepolicy AllowDuplicateFailedOnly
tctl workflow run --workflowidreusepolicy RejectDuplicate
```

### --input

Pass input for the Workflow.
Input must be in JSON format.
For multiple JSON objects, pass each in a separate `--input` option. Use `null` for null values.

Alias: `-i`

**Example**

```bash
tctl workflow run --input <json>
```

### --input_file

Pass input for the Workflow from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow run --input_file <filename>
```

### --memo_key

Pass a key for a memo.
For multiple keys, concatenate them and use spaces as separators.

**Example**

```bash
tctl workflow run --memo_key <key>
```

### --memo

Pass a memo.
A memo is information in JSON format that can be shown when the Workflow is listed.
For multiple memos, concatenate them and use spaces as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow run --memo <json>
```

### --memo_file

Pass information for a memo from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow run --memo_file <filename>
```

### --search_attr_key

Specify a [Search Attribute](/visibility#search-attribute) key.
For multiple keys, concatenate them and use pipes (`|`) as separators.

To list valid keys, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow run --search_attr_key <key>
```

### --search_attr_value

Specify a [Search Attribute](/visibility#search-attribute) value.
For multiple values, concatenate them and use pipes (`|`) as separators.
If a value is an array, use JSON format, such as `["a","b"]`, `[1,2]`, `["true","false"]`, or `["2022-06-07T17:16:34-08:00","2022-06-07T18:16:34-08:00"]`.

To list valid keys and value types, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow run --search_attr_value <value>
```

### --show_detail

Get event details.

**Example**

```bash
tctl workflow run --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow run --max_field_length <length>
```

## scan

The `tctl workflow scan` command lists [Workflow Executions](/workflows#workflow-execution).
It is faster than the `tctl workflow listall` command, but the results are not sorted.

By default, this command lists a maximum of 2000 Workflow Executions.
To set the size of a page, use the `--pagesize` option.

See also [`tctl workflow list`](#list), [`tctl workflow listall`](#listall), and [`tctl workflow listarchived`](#listarchived).

`tctl workflow scan <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow scan --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow scan --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow scan --print_memo
```

### --print_search_attr

Print the [Search Attributes](/visibility#search-attribute).

**Example**

```bash
tctl workflow scan --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow scan --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow scan --print_json
```

### --pagesize

Specify the maximum number of [Workflow Execution](/workflows#workflow-execution) to list on a page.
(By default, the `tctl workflow scan` command lists 2000 Workflow Executions per page.)

**Example**

```bash
tctl workflow scan --pagesize <value>
```

### --query

Specify an SQL-like query of [Search Attributes](/visibility#search-attribute).

Alias: `-q`

**Example**

```bash
tctl workflow scan --query <value>
```

## show

The `tctl workflow show` command shows the [Event History](/workflows#event-history) for the specified [Workflow Execution](/workflows#workflow-execution).

`tctl workflow show <modifiers>`

See also [`tctl workflow showid`](#showid).

The following modifiers control the behavior of the command.

### --workflow_id

Show the History of a [Workflow Execution](/workflows#workflow-execution) by specifying a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow show --workflow_id <id>
```

### --run_id

Show the History of a [Workflow Execution](/workflows#workflow-execution) by specifying a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow show --run_id <id>
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow show --print_datetime
```

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow show --print_raw_time
```

### --output_filename

Serialize an event to a file.

**Example**

```bash
tctl workflow show --output_filename <filename>
```

### --print_full

Print full event details.

**Example**

```bash
tctl workflow show --print_full
```

### --print_event_version

Print the event version.

**Example**

```bash
tctl workflow show --print_event_version
```

### --event_id

Print the details of a specified event.
The default value is 0.

**Example**

```bash
tctl workflow show --event_id <id>
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 500.

**Example**

```bash
tctl workflow show --max_field_length <length>
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow show --reset_points_only
```

## showid

The `tctl workflow showid` command shows the Workflow Execution Event History for the specified [Workflow Id](/workflows#workflow-id) and optional [Run Id](/workflows#run-id).

`tctl workflow showid <workflow_id> [<run_id>] <modifiers>`

This command is a shortcut for `tctl workflow show --workflow_id <workflowid> [--run_id <runid>]`.

Example:

```bashbash
tctl workflow showid <workflow_id>
```

Example output:

```bashtext
1  WorkflowExecutionStarted    {WorkflowType:{Name:HelloWorld}, ParentInitiatedEventId:0,
                                TaskQueue:{Name:HelloWorldTaskQueue, Kind:Normal},
                                Input:[Temporal], WorkflowExecutionTimeout:1h0m0s,
                                WorkflowRunTimeout:1h0m0s, WorkflowTaskTimeout:10s,
                                Initiator:Unspecified, LastCompletionResult:[],
                                OriginalExecutionRunId:f0c04163-833f-490b-99a9-ee48b6199213,
                                Identity:tctl@z0mb1e,
                                FirstExecutionRunId:f0c04163-833f-490b-99a9-ee48b6199213,
                                Attempt:1, WorkflowExecutionExpirationTime:2020-10-13
                                21:41:06.349 +0000 UTC, FirstWorkflowTaskBackoff:0s}
2  WorkflowTaskScheduled       {TaskQueue:{Name:HelloWorldTaskQueue,
                                Kind:Normal},
                                StartToCloseTimeout:10s, Attempt:1}
3  WorkflowTaskStarted         {ScheduledEventId:2, Identity:15079@z0mb1e,
                                RequestId:731f7b41-5ae4-42e4-9695-ecd857d571f1}
4  WorkflowTaskCompleted       {ScheduledEventId:2,
                                StartedEventId:3,
                                Identity:15079@z0mb1e}
5  WorkflowExecutionCompleted  {Result:[],
                                WorkflowTaskCompletedEventId:4}
```

The following modifiers control the behavior of the command.

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow showid <workflow_id> --print_datetime
```

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow showid <workflow_id> --print_raw_time
```

### --output_filename

Serialize an event to a file.

**Example**

```bash
tctl workflow showid <workflow_id> --output_filename <filename>
```

### --print_full

Print full event details.

**Example**

```bash
tctl workflow showid <workflow_id> --print_full
```

### --print_event_version

Print the event version.

**Example**

```bash
tctl workflow showid <workflow_id> --print_event_version
```

### --event_id

Print the details of a specified event.
The default value is 0.

**Example**

```bash
tctl workflow showid <workflow_id> --event_id <id>
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 500.

**Example**

```bash
tctl workflow showid <workflow_id> --max_field_length <length>
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow showid <workflow_id> --reset_points_only
```

## signal

The `tctl workflow signal` command [Signals](/encyclopedia/workflow-message-passing#sending-signals) a [Workflow Execution](/workflows#workflow-execution).

Workflows listen for Signals by their Signal name, and can be made to listen to one or more Signal names.
Workflows can also listen for SQL queries.

The Workflow below listens for instances of "HelloSignal":

```bash
tctl workflow start  --workflow_id "HelloSignal" --taskqueue HelloWorldTaskQueue --workflow_type HelloWorld --execution_timeout 3600 --input \"World\"
```

The Worker would return this output upon receiving the Signal:

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
```

Signals can also be used to change variable values.

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Hi\"
```

The output would change from the first Signal received.

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
13:58:22.352 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 2: Hi World!
```

When a Signal is sent, an await condition is made to block any Signals that contain the same input value.
However, changing the greeting in our example unblocks it:

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Welcome\"
```

Worker output:

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
13:58:22.352 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 2: Hi World!
13:59:29.097 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 3: Welcome World!
```

Sending Signals does not require a running Worker.

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Welcome\"
```

CLI output:

```text
Signal workflow succeeded.
```

The Signal request is queued inside the Temporal Server until the Worker is restarted.
If the given Signal contains the same input as before, the queued Signal will be ignored.

Complete the Workflow by sending a Signal with a "Bye" greeting:

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Bye\"
```

Check that the Workflow Execution has been completed.

```bash
tctl workflow showid HelloSignal
```

Signals are written as follows:

```bash
tctl workflow signal --workflow_id <id> <modifiers>
```

or

```bash
tctl workflow signal --query <query> <modifiers>
```

The following modifiers control the behavior of the command.
Make sure to include required modifiers in all command executions.

### --workflow_id

Specify a [Workflow Id](/workflows#workflow-id). **This modifier is required.**

Alias: `-w`

**Example**

```bash
tctl workflow signal --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow signal --run_id <id>
```

### --name

Specify the name of a [Signal](/encyclopedia/workflow-message-passing#sending-signals).

**Example**

```bash
tctl workflow signal --query <query> --name <name>
```

### --input

Pass input for the [Signal](/encyclopedia/workflow-message-passing#sending-signals).
Input must be in JSON format.

Alias: `-i`

**Example**

```bash
tctl workflow signal --query <query> --input <json>
```

### --input_file

Pass input for the [Signal](/encyclopedia/workflow-message-passing#sending-signals) from a JSON file.

**Example**

```bash
tctl workflow signal --query <query> --input_file <filename>
```

## stack

The `tctl workflow stack` command queries [Workflow Execution](/workflows#workflow-execution) with `__stack_trace` as the query type.

This command can be used to locate errors and blocks in a [Workflow Definition](/workflows#workflow-definition).

`tctl workflow stack <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow stack --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow stack --run_id <id>
```

### --input

Pass input for the query.
Input must be in JSON format.
For multiple JSON objects, concatenate them and use spaces as separators.

Alias: `-i`

**Example**

```bash
tctl workflow stack --input <json>
```

### --input_file

Pass input for the query from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow stack --input_file <filename>
```

### --query_reject_condition

Reject queries based on Workflow state.
Valid values are `not_open` and `not_completed_cleanly`.

**Example**

```bash
tctl workflow stack --query_reject_condition <value>
```

## start

The `tctl workflow start` command starts a new [Workflow Execution](/workflows#workflow-execution).
Unlike `run`, this command returns the Workflow Id and Run Id immediately after starting the Workflow.

`tctl workflow start <modifiers>`

The following modifiers control the behavior of the command.
Always include required modifiers when executing this command.

### --taskqueue

Specify a [Task Queue](/workers#task-queue).

Alias: `--t`

**Example**

```bash
tctl workflow start --taskqueue <name>
```

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow start --workflow_id <id>
```

If a Workflow is started without providing an Id, the Client generates one in the form of a UUID.
Temporal recommends using a business id rather than the client-generated UUID.

**Example**

```bash
tctl workflow start  --workflow_id "HelloTemporal1" --taskqueue HelloWorldTaskQueue --workflow_type HelloWorld --execution_timeout 3600 --input \"Temporal\"
```

### --workflow_type

Specify the name of a [Workflow Type](/workflows#workflow-type).

**Example**

```bash
tctl workflow start --workflow_type <name>
```

### --execution_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Execution](/workflows#workflow-execution) in seconds.
The default value is 0.

**Example**

```bash
tctl workflow start --execution_timeout <seconds>
```

### --workflow_task_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/workers#workflow-task) in seconds.
The default value is 10.

**Example**

```bash
tctl workflow start --workflow_task_timeout <seconds>
```

### --cron

Specify a [Cron Schedule](/workflows#cron-schedules).

**Example**

```bash
tctl workflow start --cron <string>
```

### --workflowidreusepolicy

Specify a [Workflow Id Reuse Policy](/workflows#workflow-id-reuse-policy).
Configure if the same [Workflow Id](/workflows#workflow-id) is allowed for use in new [Workflow Execution](/workflows#workflow-execution).

There are three allowed values:

- [AllowDuplicateFailedOnly](/workflows#workflow-id-reuse-policy)
- [AllowDuplicate](/workflows#workflow-id-reuse-policy)
- [RejectDuplicate] (/concepts/what-is-a-workflow-id-reuse-policy)

**Examples**

```bash
tctl workflow start --workflowidreusepolicy AllowDuplicate
tctl workflow start --workflowidreusepolicy AllowDuplicateFailedOnly
tctl workflow start --workflowidreusepolicy RejectDuplicate
```

:::note

Multiple Workflows with the same Id cannot be run at the same time

:::

### --input

Pass input for the Workflow.
Input must be in JSON format.
For multiple JSON objects, pass each in a separate `--input` option.
Use `null` for null values.

Alias: `-i`

**Example**

```bash
tctl workflow start --input <json>
```

### --input_file

Pass input for the Workflow from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow start --input_file <filename>
```

### --memo_key

Pass a key for a memo.
For multiple keys, concatenate them and use spaces as separators.

**Example**

```bash
tctl workflow start --memo_key <key>
```

### --memo

Pass information for a [memo](/workflows#memo) from a JSON file.

Memos are immutable key/value pairs that can be attached to a workflow run when starting the workflow.
Memos are visible when listing workflows.

For multiple memos, concatenate them and use spaces as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow start \
  -tq your-task-queue \
  -wt your-workflow \
  -et 60 \
  -i '"temporal"' \
  -memo_key '<key values>' \
  -memo '<value>'
```

### --memo_file

Pass information for a memo from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow start --memo_file <filename>
```

### --search_attr_key

Specify a [Search Attribute](/visibility#search-attribute) name.
For multiple names, concatenate them and use pipes (`|`) as separators.

To list valid Search Attributes, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow start --search_attr_key <key>
```

### --search_attr_value

Specify a [Search Attribute](/visibility#search-attribute) value.
For multiple values, concatenate them and use pipes (`|`) as separators.
If a value is an array, use JSON format, such as `["a","b"]`, `[1,2]`, `["true","false"]`, or `["2022-06-07T17:16:34-08:00","2022-06-07T18:16:34-08:00"]`.

To list valid Search Attributes and value types, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow start --search_attr_value <value>
```

## terminate

The `tctl workflow terminate` command terminates a [Workflow Execution](/workflows#workflow-execution).

Terminating a running Workflow Execution records a `WorkflowExecutionTerminated` event as the closing event in the History.
No more [Workflow Task](/workers#workflow-task) will be scheduled.

See also [`tctl workflow cancel`](#cancel).

`tctl workflow terminate --query <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

_Required modifier_

Specify a [Workflow Id](/workflows#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow terminate --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflows#run-id).

If `run_id` is not specified, `tctl` terminates the last Workflow Execution for the specified `workflow_id`.

Alias: `-r`

**Example**

```bash
tctl workflow terminate --run_id <id>
```

### --reason

Specify a reason for terminating the [Workflow Execution](/workflows#workflow-execution).

**Example**

```bash
tctl workflow terminate --workflow_id --reason <string>
```
